home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 011 / super.arc / SUPER.DOC < prev    next >
Text File  |  1986-06-13  |  11KB  |  282 lines
  1.                             SUPERCOMM
  2.                   IBM PC Communications drivers
  3.                        (C) Copyright 1986
  4.                           Doctor Debug
  5.                          Pittsburgh, Pa
  6.                        All Rights Reserved
  7.  
  8. ****************************************************************
  9. *                                                              *
  10. *         As  with all the Doctor's software,  SUPERCOMM       *
  11. *         has  been tested and by all indications  works       *
  12. *         as described under all reasonable  conditions.       *
  13. *         However, the good doctor cannot be responsible       * 
  14. *         for damages,  heartbreak,  outbreaks of war or       *
  15. *         acts  of  God  caused  by  the  use  of   this       *
  16. *         software.    As   it   is   FreeWare,   *free*       *
  17. *         distribution  is  encouraged  so long  as  the       *
  18. *         programs  and  documentation  are   unaltered.       *
  19. *         Please  read  the contribution information  at       *
  20. *         the end of this document.                            *
  21. *                                                              *
  22. ****************************************************************
  23.  
  24.      Anyone  who has attempted to use the BIOS Int 14  to  access 
  25. the  IBM's Communications ports knows that these routines are the 
  26. pits.   They  allow  absolutely  no  flexibility,   and  also  no 
  27. interrupt-driven  means  of reading the ports.  SUPERCOMM  is  an 
  28. answer to that problem.
  29.  
  30.      Running  the  program  SUPER.COM  is  necessary  to   access 
  31. SUPERCOMM.  This  program  can easily be placed in your  AUTOEXEC 
  32. file if you wish.  Part of the program stays resident,  replacing 
  33. Interrupt 14. 
  34.  
  35.      After  SUPER.COM has been run,  the following functions  are 
  36. available  to the new interrupt 14.  As with the BIOS  interrupt, 
  37. select the function by loading AH with the function number.
  38.  
  39. Function 0 - set Communications status
  40.      Unchanged from the BIOS Int 14. Does not activate SUPERCOMM. 
  41. This is really just kept for compatability sake.
  42.  
  43. Function 1 - Transmit Byte
  44.      A  bug  which  caused this function not to  work  with  some 
  45. modems has been fixed, but otherwise this function is the same as 
  46. the BIOS function.
  47.  
  48. Function 2 - Receive Character
  49.      Removes  a  character  from the circular  input  buffer  and 
  50. returns  it in AL.  If no character is available a timeout occurs 
  51. (bit 7 of AH will be set.)
  52.  
  53. Function 3 - Port Status
  54.      Unchanged.
  55.  
  56. Function 4 - Clear Buffer
  57.      Empties  Communications input buffer.  (The buffer is 4K  in 
  58. length)
  59.  
  60. Function 5 - Block Receive
  61.      Requests a block of data be read from the comm port.
  62.      ENTRY:    DX   =    Port (0 or 1)
  63.                CX   =    Size of block in bytes
  64.                ES:BX=    address to which data will be written
  65.  
  66.      RETURN:   CX   =    16 bit checksum of data read
  67.                AL   =    Error codes (as in original Int 14)
  68.  
  69. Function 6 - Block Send
  70.      Sends a block of data over the comm line
  71.      ENTRY:    DX   =    Port (0 or 1)
  72.                CX   =    Size of block in bytes
  73.                ES:BX=    Address of block
  74.  
  75.      RETURN:   AL   =    Error codes (as in original Int 14)
  76.  
  77. Function 7 - Buffer Status
  78.      Number of bytes waiting in the buffer returned in BX
  79.  
  80. Function 8 - Get Character
  81.      Equivalent  of  INKEY from keyboard.  Gets a byte  from  the 
  82. input  buffer if one is waiting.  Byte is returned in AL.  If  no 
  83. byte  was waiting,  AL will have 0.  Don't use this function  for 
  84. data which might be 0.
  85.  
  86. Function 9 - Set Port
  87.      Port in DX (0 or 1) will be buffered and used by  SUPERCOMM. 
  88. The other will be handled by the old BIOS routines.
  89.  
  90. Function 12 - Open SUPERCOMM port
  91.      Load  registers  as in old Interrupt 14's Function  0.  Port 
  92. specified in DX becomes active SUPERCOMM port.  System  interrupt 
  93. speed  is kicked up to 4550 times/sec for goof-proof buffering of 
  94. incoming  data.  This function must be called before any  of  the 
  95. input  or output functions are.  While the SUPERCOMM port is open 
  96. overall system speed may lag as much as 35%,  so be sure to close 
  97. the  port (using function 13) when you are through.  Leaving  the 
  98. port  open  at the end of a user program may cause a  crash  when 
  99. another program is loaded.
  100.  
  101. Function 13 - Close SUPERCOMM port
  102.      Simply load the port (0 or 1) into DX and call this routine. 
  103. System  interrupt  speed is returned to normal and  SUPERCOMM  is 
  104. deactivated until the next Function 12.
  105.  
  106. Function 14 - Peek buffer
  107.      This  handy function returns the next character in the input 
  108. buffer in AL,  but does not remove the character from the buffer. 
  109. This  means you can look ahead one char into the  buffer.  If  no 
  110. characters are waiting AL will return with a 0.
  111.  
  112.      SUPERCOMM  returns error codes in AH and AL (unless they are 
  113. returning other information).  These error codes will be the same 
  114. as  those returned by the standard Input/Output routines  of  the 
  115. old Interrupt 14. 
  116.  
  117.      All this is pretty complicated, which is why I have included 
  118. the file SUPERCOM.PAS, which contains turbo Pascal routines which 
  119. access  these functions.  DUMBTERM.PAS is a demonstration program 
  120. which  is  essentially a plain vanilla  comm  program.  Examining 
  121. these  programs  will  provide some insight  into  how  SUPERCOMM 
  122. works. Be sure to compile any Turbo programs using SUPERCOMM to a 
  123. .COM file before using!  DUMBTERM.COM has been included for those 
  124. out  there  without  a Turbo Pascal Compiler.  Also  included  is 
  125. DUMB.ASM  and DUMB.COM,  which are essentially the same thing  as 
  126. DUMBTERM.PAS only in 8086 assembler.
  127.  
  128.                          Pascal Routines
  129.                      (Found in SUPERCOM.PAS)
  130.  
  131. These routines are meant to be called by user programs. The
  132. SUPER.COM Interrupt 14 driver must have been installed to
  133. use any of these routines. Use of these routines without proper
  134. installation of SUPER.COM will produce unpredictable results.
  135. It should be relatively simple to translate these turbo routines
  136. into C or most any other language.
  137.  
  138. The integers InError and OutError will always contain the error
  139. conditions after every receive or transmit. The bits of these
  140. values are defined as:
  141.  
  142.      Bit 7 (128)        Timeout
  143.      Bit 3   (8)        Framing Error
  144.      Bit 2   (4)        Parity Error
  145.      Bit 1   (2)        Overrun Error
  146.  
  147. If the value of InError[port] is 0, then you can be sure that the
  148. last character was received without error.
  149.  
  150. The value or Port is always 1 or 2.
  151.  
  152.      Procedure InitPort(port,Baud,Parity,data_bits,stop_bits)
  153.           Baud: integer 300-9600
  154.           Parity: char, E(ven),O(dd),N(one)
  155.           Data_bits: integer, 7 or 8
  156.           Stop_bits: integer, 1 or 2
  157.  
  158.           This routine initializes the communications port
  159.           to the parameters specified and activates SUPERCOM
  160.           for that port. All of the following functions will
  161.           use the port specified here.
  162.  
  163.      Function PortStatus(port)
  164.  
  165.           This function returns the line status and modem control
  166.           status of the comm port specified. The bits returned are
  167.           defined as:
  168.  
  169.           Bit 15 (negative)  Time out (no device connected)
  170.           Bit 14 (16384)     Transmission shift register empty
  171.           Bit 13 (8192)      Transmission holding register empty
  172.           Bit 12 (4096)      Break detect
  173.           Bit 11 (2048)      Framing error
  174.           Bit 10 (1024)      Parity error
  175.           Bit 9  (512)       Overrun error
  176.           Bit 8  (256)       Data ready
  177.           Bit 7  (128)       Received line signal detect
  178.           Bit 6  (64)        Ring indicator
  179.           Bit 5  (32)        Data set ready
  180.           Bit 4  (16)        Clear to send
  181.           Bit 3  (8)         Delta receive line signal detect
  182.           Bit 2  (4)         Trailing edge ring detector
  183.           Bit 1  (2)         Delta data set ready
  184.           Bit 0  (1)         Delta clear to send
  185.  
  186.      Procedure XmitCh(ch)
  187.  
  188.           This Procedure sends the character in ch out the port
  189.           specified.
  190.  
  191.      Procedure XmitBlk(string)
  192.  
  193.           This procedure sends the entire string out the comm port.
  194.  
  195.      Procedure XmitLn(string)
  196.  
  197.           This is identical to XmitBlk, but adds a CR/LF to the
  198.           end of the block.
  199.  
  200.       Procedure RecCh(ch)
  201.  
  202.           This procedure waits until a character is available over
  203.           the comm line and then returns it in ch. If the system times
  204.           out ch will contain a nul (Ascii 0).
  205.  
  206.      Procedure RecLn(string)
  207.  
  208.           This is the equivalent of ReadLn over the comm port.
  209.           Be sure to check the InError variable to make sure the
  210.           operation did not time out (no CR was received.)
  211.  
  212.      Procedure RecBlk(number,String)
  213.  
  214.           The number of characters specified by number will be
  215.           placed into the string. Be sure to check the InError
  216.           variable to assure that the operation did not time out
  217.           before sufficient characters were received.
  218.  
  219.      Procedure GrabCh(ch)
  220.  
  221.           If a character is waiting in the receive buffer it will
  222.           be returned in ch otherwise ch will contain a nul character.
  223.  
  224.      Procedure PeekBuff(ch)
  225.  
  226.           Identical to GrabCh but the character is not removed
  227.           from the buffer.
  228.  
  229.      Procedure ClearBuff
  230.  
  231.           Empties the receive buffer
  232.  
  233.      Procedure ClosePort
  234.  
  235.           Closes the comm port and deactivates SUPERCOMM until the
  236.           next InitPort.
  237.  
  238.      Function Rlen
  239.  
  240.           Returns the number of characters currently available in the
  241.           receive buffer.
  242.  
  243.  
  244.                              Summary
  245.          (How to use SUPERCOMM in a few semi-easy steps)
  246.  
  247. 1)  Make  sure that SUPER.COM has been run so that  SUPERCOMM  is 
  248. resident. It is very difficult for software to work properly when 
  249. in is not in the computer's memory.
  250.  
  251. 2)   Your program should first issue an Interrupt 14 with AH  set 
  252. to 12 (opens the port with SUPERCOMM) and the other registers set 
  253. as  in the old BIOS Interrupt 14 Function 0.  This  assures  that 
  254. SUPERCOMM is humming away,  busily checking comm activity on  the 
  255. port specified in DX  some 4500 times a second. 
  256.  
  257. 3)    Now  you can use functions 1 through 8 to input  of  output 
  258. all the happy data over that comm port. 
  259.  
  260. 4) Before exiting the program,  issue an Interrupt 14 with AH set 
  261. to  13 (close SUPERCOMM port).  This assures that all is back  to 
  262. normal for any programs which you run later.
  263.  
  264.      Believe  me,  using  it  is a great deal  more  simple  than 
  265. writing it was!
  266.  
  267.      If you have questions,  comments, suggestions or criticisms, 
  268. you can reach me on the Neverboard,  (412) 733-4842 1200/8/N.  If 
  269. you find SUPERCOMM useful, a donation of, say, $15 may be sent to 
  270. the doctor's office:
  271.  
  272.                Doctor Debug
  273.                1 Windsor Road B-6
  274.                Pittsburgh, PA  15239
  275.  
  276.      If you use these routines in a commercial product, the above 
  277. donation  is **not** optional.  The donation will make sure  that 
  278. you  are  informed of upgrades and other pieces of  the  doctor's 
  279. software.
  280.  
  281.  
  282.